# URBANOS Shaderpack - Developer Notes & Architecture

This document serves as a guide for any developers, modders, or enthusiasts looking to understand the inner workings of the URBANOS shader engine. 

## Architectural Philosophy
URBANOS was explicitly engineered with a strict constraint: achieve AAA-quality cinematic rendering (volumetric fog, physical waves, raymarched SSR, anamorphic lens flares) while maintaining 60 FPS on low-to-mid-range legacy hardware (specifically targeting the 2GB DDR3 NVIDIA GeForce 940MX).

To achieve this, the shader strictly avoids Temporal Anti-Aliasing (TAA) and History Buffers. All effects are calculated in a single-pass (or strictly standard multi-pass without temporal feedback) to keep VRAM usage minimal and avoid the performance overhead of resolving temporal ghosting.

## Codebase Highlights

### 1. HDR Pipeline (`RGBA16F`)
The entire `colortex0` color pipeline was upgraded to `RGBA16F` to support true High Dynamic Range (HDR) values. This allows elements like the Sun and Water Sparkles to exceed the standard 1.0 color limit.
- **Micro Stars & Astigmatism (`final.fsh`):** Using the HDR buffer, the post-processing shader isolates extreme brightness values (Threshold > 1.5) to draw anamorphic flares and star-shaped blooms natively, without affecting the rest of the scene.

### 2. Physical Water (`gbuffers_water.vsh` & `composite.fsh`)
- **Vertex Displacement:** Water blocks (excluding glass) undergo real physical displacement driven by a localized Perlin noise function based on absolute world coordinates.
- **Sparkles:** High-frequency noise is applied to the specular sun reflection on water to create intense, HDR-breaking glitter, triggering the post-processing bloom.
- **Underwater Volume:** Deep blue exponential fog and caustic-driven volumetric godrays are applied based on `isEyeInWater` directly in `composite.fsh`.

### 3. Screen-Space Reflections (SSR)
Instead of a simple screen-offset trick, URBANOS uses a genuine 12-step raymarching loop in `composite.fsh` for Water, Puddles, and Glass.
- **Optimization:** To prevent "TV static" noise on low-iteration raymarching without TAA, the jitter noise was significantly minimized. 
- **1st Person Fix:** Ray intersections where `samplePos.z < -0.8` are discarded to prevent the player's own hand/item from reflecting on the water surface.

### 4. Convex Rain Droplets (`final.fsh`)
Raindrops on the camera lens are generated entirely procedurally without external textures.
- The screen space is divided into a `35.0` scaled grid.
- Each vertical column falls at a unique, slightly varied speed using a deterministic hash `fract(sin(floor(grid.x) ...))`.
- The raindrops calculate a perfect spherical refraction (`distort = -diff`), flipping the image inside the drop upside down and magnifying it (convex lens behavior).
- The drops smoothly fade out based on the OptiFine `wetness` uniform, meaning they naturally dry up after the rain stops.

### 5. Volumetric Fog & Clouds
- The atmosphere uses a smooth interpolation curve (ACES fitted Tonemapping) and custom states (Golden Hour, Noche Maravilla) defined in `atmosphere.glsl`.
- Clouds are rendered using 2D noise mapping. The sun godrays actually sample this cloud noise to allow light shafts to realistically break and pulse as clouds pass in front of the sun.

## Modification Guidelines
If you intend to modify this shader:
- Avoid adding new `colortex` buffers unless absolutely necessary, as it will spike VRAM usage on 2GB GPUs.
- If editing the rain droplets or underwater blur in `final.fsh`, remember that the image is already tonemapped at the end of the file. Insert distortion and sampling before the `acesFilm()` function.
